<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>6.3. Fetching Options and Arguments</title>
<link rel="stylesheet" href="dbstyle.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.72.0">
<link rel="start" href="index.html" title="Programmer's Reference Guide">
<link rel="up" href="zend.console.getopt.html" title="Chapter 6. Zend_Console_Getopt">
<link rel="prev" href="zend.console.getopt.rules.html" title="6.2. Declaring Getopt Rules">
<link rel="next" href="zend.console.getopt.configuration.html" title="6.4. Configuring Zend_Console_Getopt">
<link rel="chapter" href="introduction.html" title="Chapter 1. Introduction to Zend Framework">
<link rel="chapter" href="zend.acl.html" title="Chapter 2. Zend_Acl">
<link rel="chapter" href="zend.auth.html" title="Chapter 3. Zend_Auth">
<link rel="chapter" href="zend.cache.html" title="Chapter 4. Zend_Cache">
<link rel="chapter" href="zend.config.html" title="Chapter 5. Zend_Config">
<link rel="chapter" href="zend.console.getopt.html" title="Chapter 6. Zend_Console_Getopt">
<link rel="chapter" href="zend.controller.html" title="Chapter 7. Zend_Controller">
<link rel="chapter" href="zend.currency.html" title="Chapter 8. Zend_Currency">
<link rel="chapter" href="zend.date.html" title="Chapter 9. Zend_Date">
<link rel="chapter" href="zend.db.html" title="Chapter 10. Zend_Db">
<link rel="chapter" href="zend.debug.html" title="Chapter 11. Zend_Debug">
<link rel="chapter" href="zend.dojo.html" title="Chapter 12. Zend_Dojo">
<link rel="chapter" href="zend.dom.html" title="Chapter 13. Zend_Dom">
<link rel="chapter" href="zend.exception.html" title="Chapter 14. Zend_Exception">
<link rel="chapter" href="zend.feed.html" title="Chapter 15. Zend_Feed">
<link rel="chapter" href="zend.filter.html" title="Chapter 16. Zend_Filter">
<link rel="chapter" href="zend.form.html" title="Chapter 17. Zend_Form">
<link rel="chapter" href="zend.gdata.html" title="Chapter 18. Zend_Gdata">
<link rel="chapter" href="zend.http.html" title="Chapter 19. Zend_Http">
<link rel="chapter" href="zend.infocard.html" title="Chapter 20. Zend_InfoCard">
<link rel="chapter" href="zend.json.html" title="Chapter 21. Zend_Json">
<link rel="chapter" href="zend.layout.html" title="Chapter 22. Zend_Layout">
<link rel="chapter" href="zend.ldap.html" title="Chapter 23. Zend_Ldap">
<link rel="chapter" href="zend.loader.html" title="Chapter 24. Zend_Loader">
<link rel="chapter" href="zend.locale.html" title="Chapter 25. Zend_Locale">
<link rel="chapter" href="zend.log.html" title="Chapter 26. Zend_Log">
<link rel="chapter" href="zend.mail.html" title="Chapter 27. Zend_Mail">
<link rel="chapter" href="zend.measure.html" title="Chapter 28. Zend_Measure">
<link rel="chapter" href="zend.memory.html" title="Chapter 29. Zend_Memory">
<link rel="chapter" href="zend.mime.html" title="Chapter 30. Zend_Mime">
<link rel="chapter" href="zend.openid.html" title="Chapter 31. Zend_OpenId">
<link rel="chapter" href="zend.paginator.html" title="Chapter 32. Zend_Paginator">
<link rel="chapter" href="zend.pdf.html" title="Chapter 33. Zend_Pdf">
<link rel="chapter" href="zend.registry.html" title="Chapter 34. Zend_Registry">
<link rel="chapter" href="zend.rest.html" title="Chapter 35. Zend_Rest">
<link rel="chapter" href="zend.search.lucene.html" title="Chapter 36. Zend_Search_Lucene">
<link rel="chapter" href="zend.server.html" title="Chapter 37. Zend_Server">
<link rel="chapter" href="zend.service.html" title="Chapter 38. Zend_Service">
<link rel="chapter" href="zend.session.html" title="Chapter 39. Zend_Session">
<link rel="chapter" href="zend.soap.html" title="Chapter 40. Zend_Soap">
<link rel="chapter" href="zend.test.html" title="Chapter 41. Zend_Test">
<link rel="chapter" href="zend.text.html" title="Chapter 42. Zend_Text">
<link rel="chapter" href="zend.timesync.html" title="Chapter 43. Zend_TimeSync">
<link rel="chapter" href="zend.translate.html" title="Chapter 44. Zend_Translate">
<link rel="chapter" href="zend.uri.html" title="Chapter 45. Zend_Uri">
<link rel="chapter" href="zend.validate.html" title="Chapter 46. Zend_Validate">
<link rel="chapter" href="zend.version.html" title="Chapter 47. Zend_Version">
<link rel="chapter" href="zend.view.html" title="Chapter 48. Zend_View">
<link rel="chapter" href="zend.xmlrpc.html" title="Chapter 49. Zend_XmlRpc">
<link rel="appendix" href="requirements.html" title="Appendix A. Zend Framework Requirements">
<link rel="appendix" href="coding-standard.html" title="Appendix B. Zend Framework Coding Standard for PHP">
<link rel="appendix" href="copyrights.html" title="Appendix C. Copyright Information">
<link rel="index" href="the.index.html" title="Index">
<link rel="subsection" href="zend.console.getopt.fetching.html#zend.console.getopt.fetching.exceptions" title="6.3.1. Handling Getopt Exceptions">
<link rel="subsection" href="zend.console.getopt.fetching.html#zend.console.getopt.fetching.byname" title="6.3.2. Fetching Options by Name">
<link rel="subsection" href="zend.console.getopt.fetching.html#zend.console.getopt.fetching.reporting" title="6.3.3. Reporting Options">
<link rel="subsection" href="zend.console.getopt.fetching.html#zend.console.getopt.fetching.remainingargs" title="6.3.4. Fetching Non-option Arguments">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader"><table width="100%" summary="Navigation header">
<tr><th colspan="3" align="center">6.3. Fetching Options and Arguments</th></tr>
<tr>
<td width="20%" align="left">
<a accesskey="p" href="zend.console.getopt.rules.html">Prev</a> </td>
<th width="60%" align="center">Chapter 6. Zend_Console_Getopt</th>
<td width="20%" align="right"> <a accesskey="n" href="zend.console.getopt.configuration.html">Next</a>
</td>
</tr>
</table></div>
<div class="sect1" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="zend.console.getopt.fetching"></a>6.3. Fetching Options and Arguments</h2></div></div></div>
<p>
        After you have declared the options that the
        <code class="code">Zend_Console_Getopt</code> object should recognize, and supply
        arguments from the command-line or an array, you can
        query the object to find out which options were specified by a user in
        a given command-line invocation of your program.  The class implements
        magic methods so you can query for options by name.
    </p>
<p>
        The parsing of the data is deferred until the first query you make
        against the <code class="code">Zend_Console_Getopt</code> object to find out if an
        option was given, the object performs its parsing.  This allows you to
        use several method calls to configure the options, arguments, help
        strings, and configuration options before parsing takes place.
    </p>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.console.getopt.fetching.exceptions"></a>6.3.1. Handling Getopt Exceptions</h3></div></div></div>
<p>
            If the user gave any invalid options on the command-line,
            the parsing function throws a <code class="code">Zend_Console_Getopt_Exception</code>.
            You should catch this exception in your application code.
            You can use the <code class="code">parse()</code> method to force the object
            to parse the arguments.  This is useful because you can invoke
            <code class="code">parse()</code> in a <code class="code">try</code> block.  If it passes,
            you can be sure that the parsing won't throw an exception again.
            The exception thrown has a custom method <code class="code">getUsageMessage()</code>,
            which returns as a string the formatted set of usage messages for
            all declared options.
        </p>
<div class="example">
<a name="zend.console.getopt.fetching.exceptions.example"></a><p class="title"><b>Example 6.3. Catching Getopt Exceptions</b></p>
<div class="example-contents"><pre class="programlisting">&lt;?php
try {
    $opts = new Zend_Console_Getopt('abp:');
    $opts-&gt;parse();
} catch (Zend_Console_Getopt_Exception $e) {
    echo $e-&gt;getUsageMessage();
    exit;
}
            </pre></div>
</div>
<br class="example-break"><p>
            Cases where parsing throws an exception include:
        </p>
<div class="itemizedlist"><ul type="disc">
<li><p>
                    Option given is not recognized.
                </p></li>
<li><p>
                    Option requires a parameter but none was given.
                </p></li>
<li><p>
                    Option parameter is of the wrong type.
                    E.g. a non-numeric string when an integer
                    was required.
                </p></li>
</ul></div>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.console.getopt.fetching.byname"></a>6.3.2. Fetching Options by Name</h3></div></div></div>
<p>
            You can use the <code class="code">getOption()</code> method to query the value
            of an option.  If the option had a parameter, this method returns
            the value of the parameter.  If the option had no parameter but
            the user did specify it on the command-line, the method returns
            <code class="code">true</code>.  Otherwise the method returns <code class="code">null</code>.
        </p>
<div class="example">
<a name="zend.console.getopt.fetching.byname.example.setoption"></a><p class="title"><b>Example 6.4. Using getOption()</b></p>
<div class="example-contents"><pre class="programlisting">&lt;?php
$opts = new Zend_Console_Getopt('abp:');
$b = $opts-&gt;getOption('b');
$p_parameter = $opts-&gt;getOption('p');
            </pre></div>
</div>
<br class="example-break"><p>
            Alternatively, you can use the magic <code class="code">__get()</code> function
            to retrieve the value of an option as if it were a class member
            variable.  The <code class="code">__isset()</code> magic method is also
            implemented.
        </p>
<div class="example">
<a name="zend.console.getopt.fetching.byname.example.magic"></a><p class="title"><b>Example 6.5. Using __get() and __isset() magic methods</b></p>
<div class="example-contents"><pre class="programlisting">&lt;?php
$opts = new Zend_Console_Getopt('abp:');
if (isset($opts-&gt;b)) {
    echo "I got the b option.\n";
}
$p_parameter = $opts-&gt;p; // null if not set
            </pre></div>
</div>
<br class="example-break"><p>
            If your options are declared with aliases, you may use any of the
            aliases for an option in the methods above.
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.console.getopt.fetching.reporting"></a>6.3.3. Reporting Options</h3></div></div></div>
<p>
            There are several methods to report the full set of
            options given by the user on the current command-line.
        </p>
<div class="itemizedlist"><ul type="disc">
<li><p>
                    As a string: use the <code class="code">toString()</code> method.  The options
                    are returned as a space-separated string of "<code class="code">flag=value</code>"
                    pairs.  The value of an option that does not have a parameter
                    is the literal string "<code class="code">true</code>".
                </p></li>
<li><p>
                    As an array: use the <code class="code">toArray()</code> method.  The options
                    are returned in a simple integer-indexed array of strings, the flag
                    strings followed by parameter strings, if any.
                </p></li>
<li><p>
                    As a string containing JSON data: use the <code class="code">toJson()</code> method.
                </p></li>
<li><p>
                    As a string containing XML data: use the <code class="code">toXml()</code> method.
                </p></li>
</ul></div>
<p>
            In all of the above dumping methods, the flag string is the
            first string in the corresponding list of aliases.  For example,
            if the option aliases were declared like "<code class="code">verbose|v</code>",
            then the first string, "<code class="code">verbose</code>", is used as the
            canonical name of the option.  The name of the option flag does not
            include any preceding dashes.
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.console.getopt.fetching.remainingargs"></a>6.3.4. Fetching Non-option Arguments</h3></div></div></div>
<p>
            After option arguments and their parameters have been
            parsed from the command-line, there may be additional arguments
            remaining.  You can query these arguments using the
            <code class="code">getRemainingArgs()</code> method.  This method returns
            an array of the strings that were not part of any options.
        </p>
<div class="example">
<a name="zend.console.getopt.fetching.remainingargs.example"></a><p class="title"><b>Example 6.6. Using getRemainingArgs()</b></p>
<div class="example-contents"><pre class="programlisting">&lt;?php
$opts = new Zend_Console_Getopt('abp:');
$opts-&gt;setArguments(array('-p', 'p_parameter', 'filename'));
$args = $opts-&gt;getRemainingArgs(); // returns array('filename')
            </pre></div>
</div>
<br class="example-break"><p>
            <code class="code">Zend_Console_Getopt</code> supports the GNU convention that
            an argument consisting of a double-dash signifies the end of
            options.  Any arguments following this signifier must be treated as
            non-option arguments.  This is useful if you might have a non-option
            argument that begins with a dash.
            For example: "<span><strong class="command">rm -- -filename-with-dash</strong></span>".
        </p>
</div>
</div>
<div class="navfooter"><table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
<a accesskey="p" href="zend.console.getopt.rules.html">Prev</a> </td>
<td width="20%" align="center"><a accesskey="u" href="zend.console.getopt.html">Up</a></td>
<td width="40%" align="right"> <a accesskey="n" href="zend.console.getopt.configuration.html">Next</a>
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top">6.2. Declaring Getopt Rules </td>
<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
<td width="40%" align="right" valign="top"> 6.4. Configuring Zend_Console_Getopt</td>
</tr>
</table></div>
<div class="revinfo"></div>
</body>
</html>
